.TH std::char_traits 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::char_traits \- std::char_traits

.SH Synopsis
   Defined in header <string>
   template<

       class CharT

   > class char_traits;

   The char_traits class is a traits class template that abstracts basic character and
   string operations for a given character type. The defined operation set is such that
   generic algorithms almost always can be implemented in terms of it. It is thus
   possible to use such algorithms with almost any possible character or string type,
   just by supplying a customized char_traits class.

   The char_traits class template serves as a basis for explicit instantiations. The
   user can provide a specialization for any custom character types. Several explicit
   specializations are provided for the standard character types (see below), other
   specializations are not required to satisfy the requirements of CharTraits.

.SH Specializations

   The standard library provides the following standard specializations:

   Defined in header <string>
   std::char_traits<char>             the standard character traits of char
   std::char_traits<wchar_t>          the standard character traits of wchar_t
   std::char_traits<char8_t> (C++20)  the standard character traits of char8_t
   std::char_traits<char16_t> \fI(C++11)\fP the standard character traits of char16_t
   std::char_traits<char32_t> \fI(C++11)\fP the standard character traits of char32_t

   All these specializations satisfy the requirements of CharTraits.

.SH Member types

   The standard specializations define the following member types required by
   CharTraits:

  CharT                                          Member type
            char_type        int_type            off_type          pos_type          state_type
char       char        int                                    std::streampos
wchar_t    wchar_t     std::wint_t                            std::wstreampos
char8_t    char8_t     unsigned int           std::streamoff  std::u8streampos     std::mbstate_t
 char16_t  char16_t     std::uint_least16_t                    std::u16streampos
char32_t   char32_t    std::uint_least32_t                    std::u32streampos

   On top of that, the standard specializations also define the member    \fI(since C++20)\fP
   type comparison_category as std::strong_ordering.

.SH Member functions

   The standard specializations define the following static member functions required
   by CharTraits:

   assign       assigns a character
   \fB[static]\fP     \fI(public static member function)\fP
   eq           compares two characters
   lt           \fI(public static member function)\fP
   \fB[static]\fP
   move         moves one character sequence onto another
   \fB[static]\fP     \fI(public static member function)\fP
   copy         copies a character sequence
   \fB[static]\fP     \fI(public static member function)\fP
   compare      lexicographically compares two character sequences
   \fB[static]\fP     \fI(public static member function)\fP
   length       returns the length of a character sequence
   \fB[static]\fP     \fI(public static member function)\fP
   find         finds a character in a character sequence
   \fB[static]\fP     \fI(public static member function)\fP
   to_char_type converts int_type to equivalent char_type
   \fB[static]\fP     \fI(public static member function)\fP
   to_int_type  converts char_type to equivalent int_type
   \fB[static]\fP     \fI(public static member function)\fP
   eq_int_type  compares two int_type values
   \fB[static]\fP     \fI(public static member function)\fP
   eof          returns an eof value
   \fB[static]\fP     \fI(public static member function)\fP
   not_eof      checks whether a character is eof value
   \fB[static]\fP     \fI(public static member function)\fP

.SH Notes

   CharTraits does not require defining the types and functions listed above as direct
   members, it only requires types like X::type and expressions like X::func(args) are
   valid and have the required semantics. Users-defined character traits can be derived
   from other character traits classes and only override some of their members, see the
   example below.

.SH Example

   User-defined character traits may be used to provide case-insensitive comparison:


// Run this code

 #include <cctype>
 #include <iostream>
 #include <string>
 #include <string_view>

 struct ci_char_traits : public std::char_traits<char>
 {
     static char to_upper(char ch)
     {
         return std::toupper((unsigned char) ch);
     }

     static bool eq(char c1, char c2)
     {
         return to_upper(c1) == to_upper(c2);
     }

     static bool lt(char c1, char c2)
     {
          return to_upper(c1) < to_upper(c2);
     }

     static int compare(const char* s1, const char* s2, std::size_t n)
     {
         while (n-- != 0)
         {
             if (to_upper(*s1) < to_upper(*s2))
                 return -1;
             if (to_upper(*s1) > to_upper(*s2))
                 return 1;
             ++s1;
             ++s2;
         }
         return 0;
     }

     static const char* find(const char* s, std::size_t n, char a)
     {
         const auto ua{to_upper(a)};
         while (n-- != 0)
         {
             if (to_upper(*s) == ua)
                 return s;
             s++;
         }
         return nullptr;
     }
 };

 template<class DstTraits, class CharT, class SrcTraits>
 constexpr std::basic_string_view<CharT, DstTraits>
     traits_cast(const std::basic_string_view<CharT, SrcTraits> src) noexcept
 {
     return {src.data(), src.size()};
 }

 int main()
 {
     using namespace std::literals;

     constexpr auto s1 = "Hello"sv;
     constexpr auto s2 = "heLLo"sv;

     if (traits_cast<ci_char_traits>(s1) == traits_cast<ci_char_traits>(s2))
         std::cout << s1 << " and " << s2 << " are equal\\n";
 }

.SH Output:

 Hello and heLLo are equal

.SH See also

   basic_string      stores and manipulates sequences of characters
                     \fI(class template)\fP
   basic_string_view read-only string view
   \fI(C++17)\fP           \fI(class template)\fP
                     wraps a given abstract device (std::basic_streambuf)
   basic_istream     and provides high-level input interface
                     \fI(class template)\fP
                     wraps a given abstract device (std::basic_streambuf)
   basic_ostream     and provides high-level output interface
                     \fI(class template)\fP
   basic_streambuf   abstracts a raw device
                     \fI(class template)\fP
